您可以使用 Kanzi Engine 插件通过 Kanzi Engine API 创建自定义类型和消息,并在 Kanzi Studio 中使用它们。
要向 Kanzi Studio 传递有关您在 Kanzi Engine 插件中创建的自定义属性类型和消息的信息,应声明描述这些属性类型和消息的元数据。元数据使 Kanzi Engine 插件用户可以与 Kanzi Studio 中的插件内容交互。例如,元数据定义用于设置属性值的 Kanzi Studio 属性编辑器的类型,以及可供选择的值集。
仅声明您需要的元数据。Kanzi Studio 会将默认值分配给您没有设置的特性。
此表列出了您可以使用的元数据特性。
特性 (Attribute) | 描述 (Description) | 用于属性类型 | 用于消息类型 |
---|---|---|---|
displayName
|
Kanzi Studio 中显示的属性或消息名称 | x | x |
tooltip
|
属性或消息的工具提示 | x | x |
类别
|
属性、触发器或动作类别按其在 Kanzi Studio 中显示的方式命名 | x | x |
valueProvider
|
Kanzi Studio 让用户选择的属性的可能值的来源 | x | |
host
|
Kanzi Studio 推荐给属性的节点类型,以及是由 Kanzi Studio 自动添加该属性,还是让用户添加该属性 | x | |
editor
|
Kanzi Studio 编辑器用于设置属性值的类型 | x | |
DefaultValue
|
属性的默认值 | x | |
LowerBound
|
属性可以拥有的最低值 | x | |
UpperBound
|
属性可以拥有的最高值 | x | |
步进
|
Kanzi Studio 用户编辑属性值时的更改量 | x | |
Sendable
|
Kanzi Studio 是否将消息显示为动作 | x | |
Listenable
|
Kanzi Studio 是否将消息显示为触发器 | x | |
SortingIndex
|
Kanzi Studio 中其属性类别中属性的位置 | x | |
studioVisibility
|
Kanzi Studio 中是否提供属性或消息 | x | x |
LegacyName
|
Name of the property or message in the earlier versions of the plugin | x | x |
设置 Kanzi Studio 中显示的属性或消息的名称。
语法 | metadata.displayName = "name";
|
||
值 |
|
||
示例 | metadata.displayName = "Video Filename"; |
设置属性或消息的工具提示。如果用户在编写脚本或应用程序代码时需要该属性或消息的 Kanzi Engine 名称,Kanzi Studio 会附加工具提示文本。
语法 | metadata.tooltip = "text";
|
||
值 |
|
||
示例 | metadata.tooltip = "Name of the video file to be played";
|
设置 Kanzi Studio 属性 (Properties) 中显示属性的类别名称的方式。Kanzi Studio 始终首先列出 常规 (General) 和 描述 (Description) 属性类别,然后以首字母顺序列出其他属性类别。
语法 | metadata.category = "text";
|
||
值 |
|
||
示例 | metadata.category = "Video"; |
设置 Kanzi Studio 如何获取可供用户选择的属性的可能值。
语法 | metadata.valueProvider = "key:value";
|
||
值 |
|
||
示例 | //将值提供者设为 3D 节点。 //(Kanzi Studio 默认使用 Node 3D dropdown editor。) metadata.valueProvider = "ProjectObject:Node3D"; //提供包含所有可用属性类型的下拉菜单。 //(请不要设置编辑器类型。Kanzi Studio 会自动设置正确的 editor。) metadata.valueProvider = "PropertyType"; //提供用户可添加项的列表。 //(请不要设置编辑器类型。Kanzi Studio 会自动设置正确的 editor。) metadata.valueProvider = "StringList"; //提供 Kanzi 映射到整数 0 到 5 的不同维度间的方向列表。
metadata.valueProvider = "Enum : Left to Right|0;Right to Left|1;Top to Bottom|2;Bottom to Top|3;Near to Far|4;Far to Near|5";
//创建一个引用节点的字符串。
PropertyType<string> MyPlugin::NodeRefByStringProperty(kzMakeFixedString("MyPlugin.NodeRefByString"), "", 0, false,
KZ_DECLARE_EDITOR_METADATA
(
metadata.displayName = "Node Reference by String";
// 您将 valueProvider 设为 ProjectObject:Node3D 时,
// Kanzi Studio 会自动使用 Node 3D 选择器编辑器。
metadata.valueProvider = "ProjectObject:Node3D";
)); //创建引用预设件资源的字符串。
PropertyType<string> MyPlugin::PrefabRefByStringProperty(kzMakeFixedString("MyPlugin.PrefabRefByString"), "", 0, false,
KZ_DECLARE_EDITOR_METADATA
(
metadata.displayName = "Prefab Reference by String";
// 您将 valueProvider 设为 ProjectObject:PrefabTemplate 时,
// Kanzi Studio 会自动使用 Prefab 模板选择器编辑器。
metadata.valueProvider = "ProjectObject:PrefabTemplate";
)); //创建引用预设件资源的共享指针。
PropertyType<ResourceSharedPtr> MyPlugin::PrefabRefBySharedPtrProperty(kzMakeFixedString("MyPlugin.PrefabRefBySharedPtr"), ResourceSharedPtr(), 0, false,
KZ_DECLARE_EDITOR_METADATA
(
metadata.displayName = "Prefab Reference by Shared Pointer";
//您将 valueProvider 设为 ProjectObject:PrefabTemplate 时,
// Kanzi Studio 会自动使用 Prefab 模板选择器编辑器。
metadata.valueProvider = "ProjectObject:PrefabTemplate";
)); //创建引用材质资源的共享指针。
PropertyType<ResourceSharedPtr> MyPlugin::MaterialRefBySharedPtrProperty(kzMakeFixedString("MyPlugin.MaterialRefBySharedPtr"), ResourceSharedPtr(), 0, false,
KZ_DECLARE_EDITOR_METADATA
(
metadata.displayName = "Material Reference by Shared Pointer";
//您将 valueProvider 设为 ProjectObject:Material 时,
// Kanzi Studio 会自动使用 Material 下拉编辑器。
metadata.valueProvider = "ProjectObject:Material";
)); |
设置 Kanzi Studio 推荐给属性的节点类型,以及是由 Kanzi Studio 自动添加该属性,还是让用户添加该属性。
如果没有设置 host
特性,Kanzi Studio 会将该属性作为常用属性,添加到您为其创建了该属性类型的节点,并让用户将该属性添加到任何其他类型的节点。
语法 | metadata.host = "nodeType:addition";
|
||||
值 |
nodeType:addition 对。 |
||||
示例 | //将该属性添加为所有 2D 节点的常用属性。 metadata.host = "Node2D:freq"; //为所有 VideoView2D 节点自动添加该属性,并让用户添加图像 (Image) 节点的属性。 metadata.host = "VideoView2D:auto,Image2D:user"; |
设置 Kanzi Studio 用户用于设置属性值的编辑器类型。如果您没有设置编辑器,Kanzi 会分配一个默认编辑器。
如果您将 valueProvider 特性设置为 PropertyType
或 StringList
,请不要设置编辑器类型。Kanzi Studio 自动分配正确的编辑器。
如需 Kanzi Studio 属性编辑器的列表,请参阅 Kanzi Engine 插件中声明的属性类型的 Kanzi Studio 属性编辑器。
语法 | metadata.editor = "editor";
|
||
值 |
|
||
示例 | //将编辑器设为 BrowseFileTextEditor,该编辑器含有一个文本框,旁边有一个浏览 (Browse) 按钮。 metadata.editor = "BrowseFileTextEditor"; |
设置 Kanzi Studio 中显示属性或消息默认值的方式。
语法 | metadata["DefaultValue"] = "value";
|
||
值 |
|
||
示例 |
//将 Kanzi Studio 中的字符串属性的默认值设为 video.mp4。
metadata["DefaultValue"] = "video.mp4";
//将 Kanzi Studio 中的浮点属性的默认值设为 180。
metadata["DefaultValue"] = "180";
|
设置属性在 Kanzi Studio 中的最低值。通过整数和浮点属性类型使用 LowerBound
。另请参阅 UpperBound 和 步进。
语法 | metadata["LowerBound"] = "value";
|
||
值 |
|
||
示例 | //将属性的最低值设为 0。 metadata["LowerBound"] = "0"; |
设置属性在 Kanzi Studio 中的最高值。通过整数和浮点属性类型使用 UpperBound
。另请参阅 LowerBound 和 步进。
语法 | metadata["UpperBound"] = "value";
|
||
值 |
|
||
示例 | //将属性的最高值设为 360。 metadata["UpperBound"] = "360"; |
设置当 Kanzi Studio 用户编辑属性值时的更改量。通过整数和浮点属性类型使用 Step
。另请参阅 LowerBound 和 UpperBound。
语法 | metadata["Step"] = "value";
|
||
值 |
|
||
示例 | //将 Kanzi Studio 用户编辑属性值时的更改量设为 10。
metadata["Step"] = "10";
|
设置Kanzi Studio 是否在触发器动作下拉菜单中将消息显示为动作。
语法 | metadata["Sendable"] = "value"
|
||||
值 |
|
||||
示例 | //不将消息显示为动作。 metadata["Sendable"] = "False"; |
设置 Kanzi Studio 是否在添加触发器 (Add Triggers) 窗口和添加触发器 (Add Trigger) 上下文菜单中将消息显示为触发器。
语法 | metadata["Listenable"] = "value"
|
||||
值 |
|
||||
示例 | //不将消息显示为触发器。 metadata["Listenable"] = "False"; |
设置在 Kanzi Studio 属性 (Properties) 窗口中显示的属性类别中的位置。默认情况下,Kanzi Studio 根据属性类型在元类定义中的顺序,确定它们在某一属性类别中的排序。请参阅类别。
语法 | metadata["SortingIndex"] = "index"
|
||
值 |
|
||
示例 | //在该属性的属性类别中,将其作为第一个属性显示。 metadata["SortingIndex"] = "1"; |
设置 Kanzi Studio 中是否提供属性或消息。
语法 | metadata["StudioVisibility"] = "value"
|
||||||
值 |
|
||||||
示例 | //让 Kanzi Studio 不知道属性。
metadata["StudioVisibility"] = "Hidden";
|
Sets the name of the property type or message in earlier versions of the Kanzi Engine plugin.
When you rename a property type or message, use LegacyName
to inform Kanzi Studio about the change. When a Kanzi Studio user updates the Kanzi Engine plugin in a Kanzi Studio project, Kanzi Studio renames all instances of the property type or message in that project.
Syntax | metadata["LegacyName"] = "name"
|
||
Values |
|
||
Examples | // Give Kanzi Studio the name of the property type or message in the earlier versions of the plugin.
metadata["LegacyName"] = "MyOldPropertyName";
|